Docker 部署 Umami 避坑指南 & 独立博客统计二三事

📥 踩坑也快乐：Docker 部署 Umami 避坑指南 & 独立博客统计二三事

作为一个有着“小白”的技术折腾者，我一直对 Google Analytics (GA) 这类大厂的统计工具心存芥蒂。倒不是说它们不好用，而是它们收集的信息过于详尽，且数据不在自己手里，总觉得不够稳妥。

前阵子，我的 Hugo 博客换了新主题，寻思着也该把统计系统升级一下了。经过一番调研，我最终选择了 Umami。它开源、轻量、尊重隐私，最重要的是——可以私有化部署。

今天这篇博客，不讲长篇大论的原理，只讲我在用 Docker Compose 部署 Umami 过程中踩过的那些硬坑，以及我为什么强烈推荐独立博客主使用它。

🚀 为什么是 Umami？

在开始折腾之前，我们先明确目标。Umami 吸引我的点非常明确：

数据主权：数据全部存储在自己的 PostgreSQL 数据库中，不经过第三方。
轻量级：它不像 GA 那么臃肿，脚本极小，几乎不影响页面加载速度。
隐私友好：默认不收集任何个人可识别信息（PII），遵守 GDPR。
界面清爽：该有的数据（访问量、来源、设备、入口页面）一目了然，没有乱七八糟的营销推广项。

🛠️ 实操：Docker Compose 部署（附踩坑记录）

官方文档其实写得很详细，但实际操作中，因为网络环境、宿主机配置等原因，总会有意外。

这是我最终调整好的 docker-compose.yml 文件模版：

YAML

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami
    env_file: .env
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy  # 等待数据库健康检查通过再启动
    restart: always
    networks:
      - umami-network
    healthcheck:  # 新增：Umami 健康检查
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  db:
    image: postgres:15-alpine
    container_name: umami-db
    env_file: .env
    volumes:
      - ./umami-data:/var/lib/postgresql/data
    restart: always
    networks:
      - umami-network
    healthcheck:  # 新增：PostgreSQL 健康检查
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

networks:
  umami-network:
    driver: bridge

配套的 .env 文件（必须和 docker-compose.yml 同目录）

# PostgreSQL 配置（必填）
POSTGRES_PASSWORD=umami_db_password  # 自定义强密码
POSTGRES_USER=umami
POSTGRES_DB=umami

# Umami 配置（必填）
DATABASE_URL=postgresql://umami:umami_db_password@db:5432/umami  # 格式：postgresql://用户名:密码@容器名:端口/数据库名
DATABASE_TYPE=postgresql
HASH_SALT=your_random_hash_salt  # 随机字符串，比如：abc123def456ghi789（建议至少16位）

# 可选：Umami 端口（若修改容器内端口需同步）
PORT=3000

执行启动命令

# 启动服务（后台运行）
docker-compose up -d

# 初始化 Umami 数据库（首次启动必须执行）
docker-compose exec umami npm run db:migrate

⚠️ 关键踩坑点 & 解决方案：

坑 1：数据库连接失败（Wait for hash 报错）
- 现象：Umami 容器启动后，日志一直卡在等待数据库就绪，或者报错连接超时。
- 原因：PostgreSQL 容器初始化需要时间，Umami 尝试连接时数据库还没准备好。
- 解决方案：确保 depends_on 存在。如果还是不行，可以尝试在 .env 中调大数据库连接超时时间，或者在 Umami 的启动命令中加入等待脚本（最简单的方法是重启一下 Umami 容器，通常第二次就成了）。
坑 2：反向代理后的 Https 访问问题
- 现象：使用 Nginx Proxy Manager 或者 Caddy 做完反向代理后，虽然能打开界面，但静态资源加载出错，或者添加网站时一直转圈。
- 核心配置：在 .env 文件中，必须正确设置 APP_SECRET（随机长字符串）和 **HOSTNAME**（你的域名，如 stats.yourdomain.com）。同时，在反向代理配置中，确保传递了正确的 Header：
Nginx
1
2
3
4
5
# Nginx 示例配置
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
坑 3：初始密码的修改
- 提醒：默认用户名是 admin，密码是 umami。部署成功后的第一件事绝对是修改密码！ 别问我为什么知道，公网上的扫描器比你想象的要勤快得多。

📈 生活美学：技术降维后的惬意

当我在 Hugo 的配置文件中填入那行简短的统计脚本，看着 Umami 后台实时跳出的“1”（我自己踩盘子），那种亲手建立起一套系统的成就感是无与伦比的。

把硬核的技术（Docker, PSQL, Nginx）“降维”成桌面上一个清爽的仪表盘，这就是我所理解的“技术融入生活”。

现在，每天早上我会顺手点开 Umami。不需要去分析复杂的转化漏斗，只是单纯地看看昨天有多少朋友通过搜索进到了我的博客，阅读了哪篇文章。

这种感觉，就像是经营着一家深夜食堂，不需要知道食客的具体身份，只需知道他们来过，在某个角落得到了些许慰藉，便已足够。

如果你也在经营独立博客，不妨也试着“折腾”一下 Umami。数据握在自己心里的感觉，真的很棒。

☕️ 和和碎碎念：这次部署让我再次意识到了数据主权的重要性。虽然 GA 功能强大且免费，但我们往往忽略了“如果产品是免费的，那么你就是产品”这句话。Umami 给了我们一个夺回控制权的机会，虽然过程需要折腾，但结果很甜。

你现在用的是哪种统计工具？